package com.catazzz.springbootstudy.common.config;

import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * @作者: Tao
 * @日期: 2024/12/25
 * @时间: 17:23
 * @描述: Swagger配置类，用于开启和配置Swagger文档功能
 * Swagger是一个用于生成RESTful API文档的工具，它可以帮助开发者自动生成API文档，简化接口的定义和文档的维护
 */
// @EnableOpenApi - 启用Springfox的OpenAPI 3.0支持
@EnableOpenApi
@Configuration
public class SwaggerConfig {

    /**
     * 创建Docket对象并配置API文档信息
     * 该方法主要负责初始化Swagger的Docket对象，并进行相关配置，如API文档的标题、描述、联系人等信息
     *
     * @return Docket对象，包含API文档的配置信息
     */
    //  @Bean - 声明一个Spring Bean，返回值将被注册为Spring容器中的一个Bea
    @Bean
    public Docket createRestApi() {
        // 创建并配置Docket对象，用于Springfox Swagger的API文档生成
        return new Docket(DocumentationType.OAS_30)
                // 设置API文档的信息，如标题、描述、版本等
                .apiInfo(apiInfo())
                // 开始选择API文档的生成规则
                .select()
                // 选择带有@Api注解的方法作为API文档的源
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 对所有路径进行监控，生成全局的API文档
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 构建API文档的详细信息
     * 该方法主要用于构建API文档的标题、描述、联系人和版本等详细信息
     *
     * @return ApiInfo对象，包含API文档的详细信息
     */
    private ApiInfo apiInfo() {
        // 创建并返回一个ApiInfo实例，该实例包含了API的基本信息，如标题、描述、联系人信息和版本
        return new ApiInfoBuilder()
                // 设置API的标题
                .title("SpringBoot学习项目")
                // 设置API的描述
                .description("SpringBoot实战的RESTFUL接口文档说明")
                // 设置API的联系人信息，包括名称、网址和邮箱
                .contact(new Contact("刘水镜","http://baidu.com","1142553965@qq.com"))
                // 设置API的版本
                .version("1.0")
                // 构建并返回ApiInfo实例
                .build();
    }
}

